Skip to content

[docs] 책(Book) 도메인 PRD 역설계 (specs/003-book-domain)#356

Open
buzz0331 wants to merge 1 commit into
chore/spec-kit-setupfrom
003-book-domain
Open

[docs] 책(Book) 도메인 PRD 역설계 (specs/003-book-domain)#356
buzz0331 wants to merge 1 commit into
chore/spec-kit-setupfrom
003-book-domain

Conversation

@buzz0331
Copy link
Copy Markdown
Contributor

@buzz0331 buzz0331 commented May 17, 2026

Summary

운영 중인 책 도메인을 사용자 관점에서 역설계해 PRD로 정형화한 세 번째 산출물.
신규 기능 정의가 아닌 기존 구현을 "이래야 한다"로 문서화하는 작업.

Depends on #353 (Spec Kit 셋업 + 헌법 v1.0.0 비준). #353 머지 후 base를 develop으로 retarget 예정.
피드 PRD(#354)·팔로우 PRD(#355)와는 독립적으로 리뷰·머지 가능.

무엇이 추가되는가

파일 내용
specs/003-book-domain/spec.md 책 도메인 PRD (한국어, 226 줄)
specs/003-book-domain/checklists/requirements.md 사양 품질 체크리스트 (15/15 통과)

PRD 구성

  • User Stories 5건 (우선순위)
    • P1: 책 검색하기 (키워드 + 페이지, 확정 시 최근 검색어 기록)
    • P1: 책 상세 정보 보기 (ISBN, 사용자 컨텍스트 포함)
    • P1: 책 저장하고 다시 찾아보기 (토글 정합성)
    • P2: 방 생성을 위한 책 선택 (SAVED / JOINING)
    • P2: 인기 검색 책과 모집중인 방 발견
  • Functional Requirements 18건 — 검색·발견 / 상세 / 저장 / 다른 도메인 입력 제공 / 데이터 정리 / 외부 데이터 안정성
  • Success Criteria 7건 — 기술 비종속, 사용자 관찰 가능 측정치
  • Edge Cases 8건 — 잘못된 ISBN·페이지 범위·외부 일시 장애·신규 책 자동 등록·정리 안전 조건 등

핵심 결정

인기 검색 책 산정 기준 (FR-004)

신호 책 상세 조회 호출 횟수 (키워드 검색 횟수가 아님)
윈도우 전날(직전 1일)
개인화 없음 (모든 사용자 동일 결과)
갱신 일 단위 경계(자정) 이후 첫 호출부터 반영

⚠️ 화면 라벨이 "인기 검색 책"이지만 신호는 "상세 조회"라 사용자 오해 여지가 있음. 라벨 검토는 별도 백로그.

외부 도서 데이터 소스의 벤더 중립화 (FR-008, Assumptions)

현재 Naver Book API를 1차 공급원으로 사용하지만 PRD에는 명시하지 않음. "외부 도서 데이터 소스"로 추상화. 벤더 교체는 본 PRD 변경 트리거가 아님.

외부 데이터 일시 장애 시 UX (FR-018)

팔로우 PRD(#355)의 재시도 정책과 동일하게:

  • 사용자에게는 자원/외부 원인을 비노출
  • "잠시 후 다시 시도해주세요" 일반 안내만 반환
  • 내부 식별을 위한 시스템 차원의 오류 코드·로그는 유지

데이터 정리의 안전 조건 (FR-016, FR-017)

`BookCleanUpService`가 어떤 사용자·피드·방도 더 이상 참조하지 않는 책을 정리하지만, 현재 참조 중인 책 데이터가 사라져서는 안 됨.

범위 외 (의도적)

  • 방 도메인 — 책별 모집중인 방 목록의 출처. 별도 PRD에서 정의
  • 피드 도메인 — 책별 피드 목록은 피드 PRD([docs] 피드(Feed) 도메인 PRD 역설계 (specs/001-feed-features) #354) 따름
  • 최근 검색어 — 별도 검색 이력 도메인 PRD가 저장·만료·조회 정책 정의. 본 PRD는 "`isFinalized=true`인 검색 성공 시 기록"만 명시
  • 외부 메타데이터 갱신 정책 — 외부 데이터가 갱신되었을 때 시스템이 따라가는 빈도·정책은 별도 결정 사항
  • 벤더 의존(Naver API) — 추상화 계층("외부 도서 데이터 소스")으로 회피

누적 PRD 진행 상황

# 도메인 PR
001 피드(Feed) #354
002 팔로우(Follow) #355
003 책(Book) 본 PR

Test plan

  • PRD 본문이 비즈니스 어휘로 읽히는지 (벤더·구현 디테일 누출 점검)
  • 인기 검색 책 산정 기준(전날 상세 조회 호출 수)이 현재 구현과 일치하는지
  • 화면 라벨 "인기 검색 책"의 오해 여지에 대한 팀 의견
  • 데이터 정리의 안전 조건(FR-016, FR-017)이 현재 `BookCleanUpService` 동작과 일치하는지
  • 외부 도서 데이터 소스 일시 장애 UX 정책(FR-018)이 팔로우 PRD([docs] 팔로우(Follow) 도메인 PRD 역설계 (specs/002-follow-domain) #355)와 일관된지
  • 누락된 시나리오(예: 책 신고, 책 메타 수정 요청, 책별 통계 등)가 있는지 검토

[docs] 책(Book) 도메인 PRD 역설계 작성 (specs/003-book-domain)
c4c008b 
- 운영 중인 책 도메인을 사용자 관점으로 정형화 (신규 기능 정의 아님)
- User Story 5건 (P1: 검색·상세·저장, P2: 방 생성용 책 선택·인기/모집 발견)
- Functional Requirements 18건 (FR-001 ~ FR-018)
- 측정 가능한 Success Criteria 7건, Edge Cases 8건, Assumptions 8건
- 외부 도서 데이터 소스(현재 Naver Book API)는 벤더 중립으로 다룸
- 인기 검색 책 산정 기준 명문화: 전날 책 상세 조회 호출 수 기준,
  개인화 없음, 일 단위 경계 이후 갱신
  (주의: 신호가 키워드 검색이 아닌 '상세 조회'라는 점)
- 사용되지 않는 책 자동 정리(BookCleanUpService)의 안전 조건 명시
  (현재 참조 중인 책이 사라지지 않아야 함)
- 외부 데이터 일시 장애 시 사용자 경험은 팔로우 PRD와 동일 정책
  (자원/외부 원인 비노출, "잠시 후 다시 시도" 일반 안내)
- 방·피드·최근 검색어·메타 갱신 정책은 명시적 범위 외
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 17, 2026

Warning

Rate limit exceeded

@buzz0331 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 24 minutes and 58 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c6435a49-d46c-4dc0-819a-c9a6c178259f

📥 Commits

Reviewing files that changed from the base of the PR and between 2277cb3 and c4c008b.

📒 Files selected for processing (2)
  • specs/003-book-domain/checklists/requirements.md
  • specs/003-book-domain/spec.md
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch 003-book-domain

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

This was referenced May 17, 2026
Open
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@buzz0331